Virtual Smart Card

Smart card emulator written in Python

GPL version 3

Windows

macOS

Linux (Debian, Ubuntu, OpenMoko)

Virtual Smart Card emulates a smart card and makes it accessible through PC/SC. Currently the Virtual Smart Card supports the following types of smart cards:

Generic ISO-7816 smart card including secure messaging

German electronic identity card (nPA) with complete support for EAC (PACE, TA, CA)

Electronic passport (ePass/MRTD) with support for BAC

Cryptoflex smart card (incomplete)

The vpcd is a smart card reader driver for PCSC-Lite 2 and the windows smart card service. It allows smart card applications to access the vpicc through the PC/SC API. By default vpcd opens slots for communication with multiple vpicc’s on localhost on port 35963 and port 35964. But the vpicc does not need to run on the same machine as the vpcd, they can connect over the internet for example.

Although the Virtual Smart Card is a software emulator, you can use PC/SC Relay to make it accessible to an external contact-less smart card reader.

The file utils.py was taken from Henryk Plötz’s cyberflex-shell 1.

Virtual Smart Card used with PCSC-Lite or WinSCard

New in version 0.7: The Virtual Smart Card optionally brings its own standalone implementation of PC/SC. This allows accessing vpicc without PCSC-Lite. Our PC/SC implementation acts as replacement for libpcsclite which can lead to problems when used in parallel with PCSC-Lite.

Virtual Smart Card used with its own PC/SC implementation

On Android, where a traditional PC/SC framework is not available, you can use our framework to make your real contact-less smart accessible through PKCS#11. For example, an email signing application can use the PKCS#11 interface of OpenSC, which is linked against our PC/SC implementation. Then an Android App (e.g. Remote Smart Card Reader) can connect as vpicc delegating all requests and responses via NFC to a contact-less smart card that signs the mail.

Depending on your usage of the vpicc you may need to install the following:

Python 3

pyscard 4 (relaying a local smart card with –type=relay)

PyCryptodome, PBKDF2 5, PIL 8, readline 6 or PyReadline 7 (emulation of electronic passport with –type=ePass)

OpenPACE 9 (emulation of German identity card with –type=nPA)

libqrencode 10 (to print a QR code on the command line for vpcd-config; an URL will be printed if libqrencode is not available)

You can find the latest release of Virtual Smart Card on Github. Older releases are still available on Sourceforge.

Alternatively, you can clone our git repository:

The Virtual Smart Card uses the GNU Build System to compile and install. If you are unfamiliar with it, please have a look at INSTALL. If you can not find it, you are probably working bleeding edge in the repository. To generate the missing standard auxiliary files you need to additionally install libtool and pkg-config and run the following command in virtualsmartcard:

To configure (configure --help lists possible options), build and install the Virtual Smart Card now do the following:

Mac OS X 10.9 and earlier is using PCSC-Lite as smart card service which allows using the standard routine for installation on Unix.

Mac OS X 10.10 (and later) ships with a proprietary implementation of the PC/SC layer instead of with PCSC-Lite. As far as we know, this means that smart card readers must be USB devices instead of directly allowing a more generic type of reader. To make vpcd work we simply configure it to pretend being a USB smart card reader with an Info.plist:

New in version 0.7: We implemented vpcd as user mode device driver for Windows so that vpicc can directly be used in Windows’ smart card applications that use PC/SC.

For the Windows integration we extended Fabio Ottavi’s UMDF Driver for a Virtual Smart Card Reader 11 with a vpcd interface. If you choose to download the Windows binaries 14, you may directly jump to step 4.

In the CI environment, we’re building vpcd for Windows with Visual Studio Community 2019 with SDK/WDK for Windows 11. (The WDK version needs to match at least your targeted version of Windows, see this guide for installing VS with WDK 12) The vpcd installer additionally requires the WiX Toolset 3.10 13 to be installed.

Clone the git repository and make sure it is initialized with all submodules:

In Visual Studio open vpcd’s solution virtualsmartcard\win32\BixVReader.sln and ensure with the configuration manager, that the project is built for your platform (i.e. x64 or x82).

If you can successfully Build the solution, you can find the installer (BixVReaderInstaller.msi) in virtualsmartcard\win32\BixVReaderInstaller\bin\*Release

For debugging vpcd and building the driver with an older version of Visual Studio or WDK please see Fabio Ottavi’s UMDF Driver for a Virtual Smart Card Reader 11 for details.

All of Fabio’s card connectors are still available, but inactive by default (see Configuring vpcd on Windows below).

To import the installer’s test signing certificate, double click BixVReader.cer and add it to the Trusted Root Certification Authority and the Trusted Publishers at the Local Computer” (not the *Current User).

On the commandline, you could do this as follows:

Feel free to remove the certificate from the certificate stores once the device is installed.

To install vpcd, double click BixVReaderInstaller.msi.

The protocol between vpcd and vpicc as well as details on extending vpicc with a different card emulator are covered in Creating a Virtual Smart Card. Here we will focus on configuring and running the provided modules.

The configuration file of vpcd is usually placed into /etc/reader.conf.d/. For older versions of PCSC-Lite you need to run update-reader.conf to update pcscd’s main configuration file. The PC/SC daemon should read it and load the vpcd on startup. In debug mode pcscd -f -d should say something like “Attempting startup of Virtual PCD” when loading vpcd.

By default, vpcd opens a socket for vpicc and waits for incoming connections. The port to open should be specified in CHANNELID and DEVICENAME:

If the first part of the DEVICENAME is different from /dev/null, vpcd will use this string as a hostname for connecting to a waiting vpicc. vpicc needs to be started with –reversed in this case.

Mac OS X 10.9 and earlier is using PCSC-Lite as smart card service which allows using the standard routine for configuration on Unix.

On Mac OS X 10.10 you should have configured the generation of Info.plist at compile time. Now do the following for registering vpcd as USB device:

Choose an USB device (e.g. mass storage, phone, mouse, …), which will be used to start vpcd. Plug it into the computer.

Run the following command to get the device’s product and vendor ID:

Change /usr/local/libexec/SmartCardServices/drivers/ifd-vpcd.bundle/Info.plist to match your product and vendor ID:

Note that ifdFriendlyName can be used in the same way as DEVICENAME described above.

Restart the PC/SC service:

Now, every time you plug in your USB device vpcd will be started. It will be stopped when you unplug the device.

To verify the installation, execute:

In case of a problem, inspect the logs:

The configuration file BixVReader.ini of vpcd is installed to C:\Windows (%SystemRoot%). The user mode device driver framework (WUDFHost.exe) should read it automatically and load the vpcd on startup. The Windows Device Manager mmc devmgmt.msc should list the Bix Virtual Smart Card Reader.

vpcd opens a socket for vpicc and waits for incoming connections. The port to open should be specified in TCP_PORT:

Currently it is not possible to configure the Windows driver to connect to an vpicc running with –reversed.

The compiled Windows binaries 14 of vpicc include OpenPACE. The other dependencies listed above need to be installed seperately. You can start the vpicc via python.exe vicc.py. On all other systems an executable script vicc is installed using the autotools.

The vpicc option –help gives an overview about the command line switches:

New in version 0.7: We implemented vpcd-config which tries to guess the local IP address and outputs vpcd’s configuration. vpicc’s options should be chosen accordingly (–hostname and –port) vpcd-config also prints a QR code for configuration of the Remote Smart Card Reader.

When vpcd and vpicc are connected you should be able to access the card through the PC/SC API. You can use the opensc-explorer or pcsc_scan for testing. In Virtual Smart Card’s root directory we also provide scripts for testing with npa-tool 15 and PCSC-Lite’s smart card reader driver tester.

A simple tool to test BAC is available for Python 2.7. On Ubuntu, its requiremets are installed as follows:

Now we can create and run a small script: